home *** CD-ROM | disk | FTP | other *** search
/ BCI NET / BCI NET Dec 94.iso / archives / programming / libraries / mui20dev.lha / MUI / Developer / Autodocs / MUI_Notify.doc < prev    next >
Text File  |  1994-02-11  |  16KB  |  542 lines
  1. TABLE OF CONTENTS
  2.  
  3. Notify.mui/Notify.mui
  4. Notify.mui/MUIM_CallHook
  5. Notify.mui/MUIM_KillNotify
  6. Notify.mui/MUIM_MultiSet
  7. Notify.mui/MUIM_Notify
  8. Notify.mui/MUIM_Set
  9. Notify.mui/MUIM_SetAsString
  10. Notify.mui/MUIM_WriteLong
  11. Notify.mui/MUIM_WriteString
  12. Notify.mui/MUIA_AppMessage
  13. Notify.mui/MUIA_HelpFile
  14. Notify.mui/MUIA_HelpLine
  15. Notify.mui/MUIA_HelpNode
  16. Notify.mui/MUIA_NoNotify
  17. Notify.mui/MUIA_Revision
  18. Notify.mui/MUIA_UserData
  19. Notify.mui/MUIA_Version
  20. Notify.mui/Notify.mui
  21.  
  22.     Notify class is superclass of all other MUI classes.
  23.     It's main purpose is to handle MUI's notification
  24.     mechanism, but it also contains some other methods
  25.     and attributes useful for every object.
  26. Notify.mui/MUIM_CallHook
  27.  
  28.     NAME
  29.     MUIM_CallHook
  30.  
  31.     SYNOPSIS
  32.     DoMethod(obj,MUIM_CallHook,struct Hook *Hook, ULONG param1, /* ... */);
  33.  
  34.     FUNCTION
  35.     Call a standard amiga callback hook, defined by a Hook
  36.     structure. Together with MUIM_Notify, you can easily
  37.     bind hooks to buttons, your hook will be called when
  38.     the button is pressed.
  39.  
  40.     The hook will be called with a pointer to the hook
  41.     structure in a0, a pointer to the calling object in a2
  42.     and a pointer to the first parameter in a1.
  43.  
  44.     INPUTS
  45.     Hook       pointer to a struct Hook.
  46.     param1,... zero or more parameters. The hook function will
  47.                receive a pointer to the first parameter in
  48.                register a1.
  49.  
  50.     EXAMPLE
  51.  
  52.     standalone:
  53.  
  54.     DoMethod(obj,MUIM_CallHook,&hookstruct,13,42,"foobar","barfoo");
  55.  
  56.     within a notification statement:
  57.  
  58.     DoMethod(propobj,MUIM_Notify,MUIA_Prop_First,MUIV_EveryTime,
  59.              propobj,3,MUIM_CallHook,&prophook,MUIV_TriggerValue);
  60.  
  61.     prophook will be called every time the knob is moving and gets
  62.     a pointer to the knobs current level in a1.
  63. Notify.mui/MUIM_KillNotify
  64.  
  65.     NAME
  66.     MUIM_KillNotify
  67.  
  68.     SYNOPSIS
  69.     DoMethod(obj,MUIM_KillNotify,ULONG TrigAttr);
  70.  
  71.     FUNCTION
  72.     MUIM_KillNotify kills previously given notifications on specific 
  73.     attributes.
  74.  
  75.     INPUTS
  76.     TrigAttr - Attribute for which the notify was specified. If you
  77.                set up more than one notify for an attribute, only
  78.                the first one will be killed.
  79.  
  80.     EXAMPLE
  81.     DoMethod(button,MUIM_KillNotify,MUIA_Pressed);
  82.  
  83.     SEE ALSO
  84.     MUIM_Notify
  85. Notify.mui/MUIM_MultiSet
  86.  
  87.     NAME
  88.     MUIM_MultiSet
  89.  
  90.     SYNOPSIS
  91.     DoMethod(obj,MUIM_MultiSet,ULONG attr, ULONG val, APTR obj, /* ... */);
  92.  
  93.     FUNCTION
  94.     Set an attribute for multiple objects.
  95.     Receiving an attribute/value pair and a list of objects,
  96.     this method sets the new value for all the objects in the list.
  97.     This is especially useful for disabling/enabling lots of
  98.     objects with one singe function call.
  99.  
  100.     The object that executes this method isn't affected!
  101.  
  102.     Note: This method was implemented in version 7 of notify class.
  103.  
  104.     INPUTS
  105.     attr     attribute to set.
  106.     value    new value for the attribute.
  107.     obj, ... list of MUI objects, terminated with a NULL pointer.
  108.  
  109.     EXAMPLE
  110.     /* disable all the address related gadgets... */
  111.  
  112.     DoMethod(xxx, MUIM_MultiSet, MUIA_Disabled, TRUE,
  113.        ST_Name, ST_Street, ST_City, ST_Country, ST_Phone, NULL);
  114.  
  115.     /* note that the xxx object doesn't get disabled! */
  116.  
  117.     SEE ALSO
  118.     MUIM_Set, MUIM_Notify
  119. Notify.mui/MUIM_Notify
  120.  
  121.     NAME
  122.     MUIM_Notify
  123.  
  124.     SYNOPSIS
  125.     DoMethod(obj,MUIM_Notify,ULONG TrigAttr, ULONG TrigVal, APTR DestObj, ULONG FollowParams, /* ... */);
  126.  
  127.     FUNCTION
  128.     Add a notification event handler to an object. Notification
  129.     is essential for every MUI application.
  130.  
  131.     A notification statement consists of a source object,
  132.     an attribute/value pair, a destination object and a
  133.     notification method. The attribute/value pair belongs
  134.     to the source object and determines when the notification
  135.     method will be executed on the destination object.
  136.  
  137.     Whenever the source object gets the given attribute set to
  138.     the given value (this can happen because of the user
  139.     pressing some gadgets or because of your program explicitly
  140.     setting the attribute with SetAttrs()), the destination
  141.     object will execute the notification method.
  142.  
  143.     With some special values, you can trigger the notification
  144.     every time the attribute is changing. In this case, you
  145.     can include the triggering attributes value within the
  146.     notification method. See below.
  147.  
  148.     One big problem with notification are endless loops.
  149.     Imagine you have a prop gadget and want to show its
  150.     state with a gauge object. You connect MUIA_Prop_First
  151.     with MUIA_Gauge_Max and everything is fine, the gauge
  152.     gets updated when the user drags around the gadget. On
  153.     the other hand, if your program sets the gauge to a new
  154.     value, you might want your prop gadget to immediately
  155.     show this change and connect MUIA_Gauge_Max width
  156.     MUIA_Prop_First. Voila, a perfect endless loop.
  157.  
  158.     To avoid these conditions, MUI always checks new
  159.     attribute values against the current state and
  160.     cancels notification when both values are equal.
  161.     Thus, setting MUIA_Prop_First to 42 if the prop
  162.     gadgets first position is already 42 won't trigger
  163.     any notification event.
  164.  
  165.     INPUTS
  166.     TrigAttr     attribute that triggers the notification.
  167.  
  168.     TrigValue    value that triggers the notification. The
  169.                  special value MUIV_EveryTime makes MUI execute
  170.                  the notification method every time when
  171.                  TrigAttr changes. In this case, the special
  172.                  value MUIV_TriggerValue in the notification
  173.                  method will be replaced with the value
  174.                  that TrigAttr has been set to. You can use
  175.                  MUIV_TriggerValue up to four times in one
  176.                  notification method.
  177.  
  178.     DestObj      object on which to perform the notification
  179.                  method.
  180.  
  181.     FollowParams number of following parameters. If you e.g.
  182.                  have a notification method with three parts
  183.                  (maybe MUIM_Set,attr,val), you have to set
  184.                  FollowParams to 3. This allows MUI to copy
  185.                  the complete notification method into a
  186.                  private buffer for later use.
  187.  
  188.     ...          following is the notification method.
  189.  
  190.     EXAMPLE
  191.  
  192.     /*
  193.     ** Every time when the user releases a button
  194.     ** (and the mouse is still over it), the button object
  195.     ** gets its MUIA_Pressed attribute set to FALSE.
  196.     ** Thats what a program can react on with notification,
  197.     ** e.g. by openening a window.
  198.     */
  199.  
  200.     DoMethod(buttonobj,MUIM_Notify,
  201.        MUIA_Pressed, FALSE,                /* attribute/value pair */
  202.        windowobj,                          /* destination object   */
  203.        3,                                  /* 3 following words    */
  204.        MUIM_Set, MUIA_Window_Open, TRUE);  /* notification method  */
  205.  
  206.     /*
  207.     ** Lets say we want to show the current value of a
  208.     ** prop gadget somewhere in a text field:
  209.     */
  210.  
  211.     DoMethod(propobj,MUIM_Notify,      /* notification is triggered   */
  212.        MUIA_Prop_First, MUIV_EveryTime /* every time the attr changes */
  213.        textobj                         /* destination object */
  214.        4,                              /* 4 following words  */
  215.        MUIM_SetAsString, MUIA_Text_Contents,
  216.        "value is %ld !", MUIV_TriggerValue);
  217.        /* MUIV_TriggerValue will be replaced with the
  218.           current value of MUIA_Prop_First */
  219.  
  220.     /*
  221.     ** Inform our application when the user hits return
  222.     ** in a string gadget:
  223.     */
  224.  
  225.     DoMethod(stringobj,MUIM_Notify,
  226.        MUIA_String_Acknowledge, MUIV_EveryTime,
  227.        appobj, 2, MUIM_Application_ReturnID, ID_FOOBAR);
  228. Notify.mui/MUIM_Set
  229.  
  230.     NAME
  231.     MUIM_Set
  232.  
  233.     SYNOPSIS
  234.     DoMethod(obj,MUIM_Set,ULONG attr, ULONG val);
  235.  
  236.     FUNCTION
  237.     Set an attribute to a value. Normally, you would set
  238.     attributes with intuition.library SetAttrs() or with
  239.     the OM_SET method as with any other boopsi objects.
  240.     But since these calls need a complete tag list, not
  241.     just a single attribute/value pair, they are not
  242.     useful within a MUIM_Notify method.
  243.  
  244.     INPUTS
  245.     attr  attribute you want to set.
  246.     val   value to set the attribute to.
  247.  
  248.     EXMAPLE
  249.     DoMethod(strobj,MUIM_Set,MUIA_String_Contents,"foobar");
  250.     and
  251.     SetAttrs(strobj,MUIA_String_Contents,"foobar",TAG_DONE);
  252.     are equal.
  253.  
  254.     SEE ALSO
  255.     MUIM_SetAsString, MUIM_Notify
  256. Notify.mui/MUIM_SetAsString
  257.  
  258.     NAME
  259.     MUIM_SetAsString
  260.  
  261.     SYNOPSIS
  262.     DoMethod(obj,MUIM_SetAsString,ULONG attr, char *format, ULONG val, /* ... */);
  263.  
  264.     FUNCTION
  265.     Set a (text kind) attribute to a string. This can be useful
  266.     if you want to connect a numeric attribute of an object with
  267.     a text attribute of another object.
  268.  
  269.     INPUTS
  270.     attr    attribute to set.
  271.     format  C like formatting string, remember to use "%ld" !
  272.     val,... one or more paremeters for the format string.
  273.  
  274.     EXAMPLE
  275.  
  276.     stand alone:
  277.  
  278.     DoMethod(txobj,MUIM_SetAsString,MUIA_Text_Contents,
  279.              "My name is %s and I am %ld years old.",name,age);
  280.  
  281.     within a notification statement:
  282.  
  283.     DoMethod(propobj,MUIM_Notify,MUIA_Prop_First,MUIV_EveryTime,
  284.              txobj,4,MUIM_SetAsString,MUIA_Text_Contents,
  285.              "prop gadget shows %ld.",MUIV_TriggerValue);
  286.  
  287.     SEE ALSO
  288.     MUIM_Set, MUIM_Notify
  289. Notify.mui/MUIM_WriteLong
  290.  
  291.     NAME
  292.     MUIM_WriteLong
  293.  
  294.     SYNOPSIS
  295.     DoMethod(obj,MUIM_WriteLong,ULONG val, ULONG *memory);
  296.  
  297.     FUNCTION
  298.     This method simply writes a longword somewhere to memory.
  299.     Although this seems quite useless, it might become handy
  300.     if used within a notify statement. For instance, you could
  301.     easily connect the current level of a slider with some
  302.     member of your programs data structures.
  303.  
  304.     INPUTS
  305.     val    - value to write
  306.     memory - location to write the value to
  307.  
  308.     EXAMPLE
  309.  
  310.     /* Let the slider automagically write its level to a variable */
  311.  
  312.     static LONG level;
  313.  
  314.     DoMethod(slider,MUIM_Notify,MUIA_Slider_Level,MUIV_EveryTime,
  315.        slider,3,MUIM_WriteLong,MUIV_TriggerValue,&level);
  316.  
  317.     SEE ALSO
  318.     MUIM_WriteString, MUIM_Notify
  319. Notify.mui/MUIM_WriteString
  320.  
  321.     NAME
  322.     MUIM_WriteString
  323.  
  324.     SYNOPSIS
  325.     DoMethod(obj,MUIM_WriteString,char *str, char *memory);
  326.  
  327.     FUNCTION
  328.     This method simply copies a string somewhere to memory.
  329.     Although this seems quite useless, it might become handy
  330.     if used within a notify statement. For instance, you could
  331.     easily connect the current contents of a string gadget
  332.     with some member of your programs data structures.
  333.  
  334.     Note: The string is copied with strcpy(), you must assure
  335.               that the destination points to enough memory.
  336.  
  337.     INPUTS
  338.     str    - string to copy
  339.     memory - location to write the value to
  340.  
  341.     EXAMPLE
  342.  
  343.     static char buffer[256];
  344.  
  345.     DoMethod(string,MUIM_Notify,MUIA_String_Contents,MUIV_EveryTime,
  346.        string,3,MUIM_WriteString,MUIV_TriggerValue,buffer);
  347.  
  348.     SEE ALSO
  349.     MUIM_WriteLong, MUIM_Notify
  350. Notify.mui/MUIA_AppMessage
  351.  
  352.     NAME
  353.     MUIA_AppMessage -- [..G], struct AppMessage *
  354.  
  355.     FUNCTION
  356.     When your window is an AppWindow, i.e. you have set the
  357.     MUIA_Window_AppWindow attribute to TRUE, you will be able
  358.     to get AppMessages by listening to MUIA_AppMessage.
  359.     Whenever an AppMessage arrives, this attribute will
  360.     be set to a pointer to that message.
  361.  
  362.     MUIA_AppMessage is object specific. You can e.g. set up
  363.     different notifications for different objects in your window,
  364.     they will only get exectued when icons are dropped over the
  365.     specific object.
  366.  
  367.     If you wait on MUIA_AppMessage with a window object, your
  368.     notify will always get executed when icons are dropped on
  369.     the window.
  370.  
  371.     Notes:
  372.  
  373.     - You should use the MUIM_CallHook method to call a
  374.       hook function when an AppMessage arrives (see below).
  375.       The pointer to the AppMessage is only as long as the
  376.       notification method is executed.
  377.  
  378.     - AppWindows are only possible on the workench screen.
  379.  
  380.  
  381.     EXAMPLE
  382.  
  383.     /* Call the AppMsgHook when an icon is dropped on a listview */
  384.  
  385.     DoMethod(lvobj,MUIM_Notify,MUIA_AppMessage,MUIV_EveryTime,
  386.              lvobj,3,MUIM_CallHook,&AppMsgHook,MUIV_TriggerValue);
  387.  
  388.     /* Call the AppMsgHook when an icon is dropped on the window */
  389.  
  390.     DoMethod(winobj,MUIM_Notify,MUIA_AppMessage,MUIV_EveryTime,
  391.              winobj,3,MUIM_CallHook,&AppMsgHook,MUIV_TriggerValue);
  392.  
  393.     SEE ALSO
  394.     MUIA_Window_AppWindow, MUIA_Application_DropObject, MUIM_CallHook
  395. Notify.mui/MUIA_HelpFile
  396.  
  397.     NAME
  398.     MUIA_HelpFile -- [ISG], STRPTR
  399.  
  400.     FUNCTION
  401.     This attribute allows defining an AmigaGuide style file
  402.     to be displayed when the user requests online help.
  403.  
  404.     When the HELP button is pressed, MUI tries to obtain
  405.     MUIA_HelpFile from the current object (the one under
  406.     the mouse pointer). If MUIA_HelpFile is not defined,
  407.     MUI continues asking the parent object for this
  408.     attribute (usually a group, but remember: the parent
  409.     of a windows root object is the window itself, the
  410.     parent of a window is the application).
  411.  
  412.     When a non NULL MUIA_HelpFile is found, the same procedure
  413.     is applied to MUIA_HelpNode and MUIA_HelpLine. Then MUI
  414.     puts the application to sleep and displays the file at
  415.     the position specified width MUIA_HelpNode and/or MUIA_HelpLine.
  416.  
  417.     This behaviour allows you e.g. to define one MUIA_HelpFile
  418.     for your application object and different help nodes
  419.     and lines for your applications windows and/or gadgets.
  420.  
  421.     EXAMPLE
  422.  
  423.     ApplicationObject,
  424.        ...
  425.        MUIA_HelpFile, "progdir:myapp.guide",
  426.        ...,
  427.        SubWindow, WindowObject,
  428.           MUIA_Window_Title, "Prefs Window",
  429.           ...,
  430.           MUIA_HelpNode, "prefs-section",
  431.           ...,
  432.           End,
  433.  
  434.        SubWindow, WindowObject,
  435.           MUIA_Window_Title, "Play Window",
  436.           ...
  437.           MUIA_HelpNode, "play-section",
  438.           ...
  439.           WindowContents, VGroup,
  440.              ...,
  441.              Child, StringObject,
  442.                 MUIA_HelpNode, "play-string",
  443.                 ...,
  444.                 End,
  445.              End,
  446.           End,
  447.        End;
  448.  
  449.     In this case, the user will get the prefs-section chapter
  450.     of "myapp.guide" when he requests help in the Prefs window,
  451.     the play-string chapter when he requests help over the
  452.     string gadget in the Play window or the play-section
  453.     chapter somewhere else in the Play window.
  454.  
  455.     SEE ALSO
  456.     MUIA_HelpNode, MUIA_HelpLine
  457. Notify.mui/MUIA_HelpLine
  458.  
  459.     NAME
  460.     MUIA_HelpLine -- [ISG], LONG
  461.  
  462.     FUNCTION
  463.     Define a line in a help file specified with MUIA_HelpFile.
  464.  
  465.     SEE ALSO
  466.     MUIA_HelpFile, MUIA_HelpNode
  467. Notify.mui/MUIA_HelpNode
  468.  
  469.     NAME
  470.     MUIA_HelpNode -- [ISG], STRPTR
  471.  
  472.     FUNCTION
  473.     Define a node in a help file specified with MUIA_HelpFile.
  474.  
  475.     SEE ALSO
  476.     MUIA_HelpFile, MUIA_HelpLine
  477. Notify.mui/MUIA_NoNotify
  478.  
  479.     NAME
  480.     MUIA_NoNotify -- [.S.], BOOL
  481.  
  482.     FUNCTION
  483.     If you set up a notify on an attibute to react on user input,
  484.     you will also recognize events when you change this attribute
  485.     under program control with SetAttrs(). Setting MUIA_NoNotify
  486.     together with your attribute will prevent this notification
  487.     from being triggered.
  488.  
  489.     NOTE
  490.     MUIA_NoNotify is a "one time" attribute. Its only valid during
  491.     the current SetAttrs() call!
  492.  
  493.     EXAMPLE
  494.     SetAttrs(slider,MUIA_NoNotify,TRUE,MUIA_Slider_Level,26,TAG_DONE);
  495. Notify.mui/MUIA_Revision
  496.  
  497.     NAME
  498.     MUIA_Revision -- [..G], LONG
  499.  
  500.     FUNCTION
  501.     Get the revision number of an objects class. Although
  502.     MUIA_Revision is documented at notify class, you will
  503.     of course receive the revision number of the objects true
  504.     class.
  505.  
  506.     EXAMPLE
  507.     strobj = MUI_NewObject(MUIC_String,...,TAG_DONE);
  508.         ...
  509.     get(strobj,MUIA_Version ,&v);
  510.     get(strobj,MUIA_Revision,&r);
  511.     printf("String class version %ld.%ld\n",v,r);
  512.  
  513.     SEE ALSO
  514.     MUIA_Version
  515. Notify.mui/MUIA_UserData
  516.  
  517.     NAME
  518.     MUIA_UserData -- [ISG], ULONG
  519.  
  520.     FUNCTION
  521.     A general purpose value to fill in any kind of information.
  522. Notify.mui/MUIA_Version
  523.  
  524.     NAME
  525.     MUIA_Version -- [..G], LONG
  526.  
  527.     FUNCTION
  528.     Get the version number of an objects class. Although
  529.     MUIA_Version is documented at notify class, you will
  530.     of course receive the version number of the objects true
  531.     class.
  532.  
  533.     EXAMPLE
  534.     strobj = MUI_NewObject(MUIC_String,...,TAG_DONE);
  535.         ...
  536.     get(strobj,MUIA_Version ,&v);
  537.     get(strobj,MUIA_Revision,&r);
  538.     printf("String class version %ld.%ld\n",v,r);
  539.  
  540.     SEE ALSO
  541.     MUIA_Revision
  542.